|
Optional
|
| The Translation Kit Table of Contents | The Translation Kit Index |
Declared in: be/translation/TranslatorAddOn.h
Library: libtranslation.so
This section describes the functions and data that a translator add-on must (or can) supply. The translator add-ons that you create and install are loaded into a BTranslatorRoster object through its Default() or AddTranslators() function.
You compile your add-on as a shared library, link against libtranslation.so, and install the add-on object file in the Translators subdirectory of B_USER_ADDONS_DIRECTORY.
The table below briefly lists the translator add-on symbols:
| Symbol | Required? | Description |
|---|---|---|
| translatorInfo | yes | long description of translator |
| translatorName | yes | short name of translator |
| translatorVersion | yes | translator version number |
| Identify() | yes | identify data in a BPositionIO |
| Translate() | yes | translate data from one format to another |
| inputFormats | no | list of supported input formats |
| outputFormats | no | list of supported output formats |
| GetConfigMessage() | no | save current configuration in a BMessage |
| MakeConfig() | no | create a view for user-configuration of translator |
|
|
This function stores the current configuration in the ioExtension in such a manner that it may be flattened, unflattened, and then passed to Translate() as an ioExtension.
|
|
If the translator understands how to convert the data contained in inSource to media type outType, it fills outInfo with details about the input format and return B_OK. If it doesn't know how to translate the data, it returns B_NO_TRANSLATOR.
The quality and capability fields in outInfo are used by the Translation Kit in selecting the best suited translator for a given translation, so it is best to be conservative in choosing these values.
If the media format doesn't have a type code in <be/support/TypeConstants.h> (as will most likely be the case), choose a reasonable value. For example, the Targa handler included with the BeOS distribution uses the type code 'TGA '.
The translator need not fill in the translator field in outInfo; BTranslatorRoster fills in this value for you.
Remember that inSource may be arriving from any source, including a live network feed. It's therefore best to steer clear of calls such as BPositionIO::Size() which force all the data out of the stream. Similarly, it is good practice to read only as much of the stream as you need.
inFormat, if it is not NULL, is provided as a hint to the format of the data in inSource. Since it is only a hint, the data may very well be in some other format.
ioExtension, if it is not NULL, contains additional information for the add-on. It is described at length in the section in BTranslatorRoster titled "Configuration".
outType may be zero, in which case any output format is acceptable.
|
|
This function creates a new BView through which the user configures the add-on. For example, it could be used to control the degree of image compression used or the video frame rate. The bounds of the view are returned in outExtent, although it can be resized at will by an external source. Changes to the configuration take effect immediately, although translations should be carried out with the same parameters throughout.
|
|
The translator translates data from inSource to format outType, writing the output to outDestination. outType may be zero, in which case it is assumed to be the default format type for the media group. As in Identify(), inInfo serves as a hint to the format of the data in inSource. ioExtension fills its usual role as a container of configuration information. The function returns B_OK if it's able to convert the data successfully. If it's unable to do so, it returns either B_NO_TRANSLATOR or an error value as appropriate.
|
|
These arrays tell BTranslatorRoster which formats the add-on supports. If they are not exported by the translator, the add-on's Identify() will be called each time an application requests a translation. Each array ends in an empty translation_format structure, so a typical inputFormats would look like:
translation_format inputFormats[] = {
{ 'TGA ', B_TRANSLATOR_BITMAP, 0.6, 0.5, "image/targa",
"Targa bitmap format" },
{ B_TRANSLATOR_BITMAP, B_TRANSLATOR_BITMAP, 0.4, 0.6, "image/x-be-bitmap",
"Be Bitmap format" },
{ 0, 0, 0, 0, 0, 0 }
};
and similarly for outputFormats.
|
|
translatorInfo returns a pointer to the translator's long name, e.g. "aiff translator by the Pie Man (pie@the.man)".
translatorName returns a pointer to the translator's short name, e.g. "aiff translator". The short name should be appropriate for display in a menu.
translatorVersion gives an "MM.mm" version number for the translator. For example, a TranslatorVersion() of 314 is interpreted as version 3.14.
| The Translation Kit Table of Contents | The Translation Kit Index |
Copyright © 2000 Be, Inc. All rights reserved..